Coding Style

TLDR

• 命名規則：除變數外多採 Pascal Case；欄位（Fields）除特定情況外採 Camel Case，且不加底線前綴；Interface 須以「I」開頭。
• 縮寫規則：三個單字以上縮寫，僅首字母大寫；兩個單字縮寫，依 Pascal/Camel Case 決定首字母，後續字母小寫。
• 排序規則：成員排序優先級為：欄位 > 建構子 > 解構子 > Delegate > Event > Property > Indexer > Method。
• 排版風格：左大括弧置於同一行；二元運算子換行時置於新行開頭；賦值運算子（=）換行時置於行尾。
• 註解規範：傾向說明「為什麼」而非「做什麼」；Private 成員無需文件註解。
• 檔案結尾：檔案末端應保留一個空行，以符合 Unix/Linux 換行規範。

---

Naming Rules

在 C# 命名規範中，應遵循以下原則：

• Pascal Case：適用於類別、方法、屬性、Public/Internal Fields、Constants 及 Static Readonly Fields。
• Camel Case：適用於區域變數與一般 Fields。
• 前綴限制：Fields 不應加上「」、「m」或「s_」等前綴。
• Interface：名稱開頭必須加上「I」。
• 泛型參數：單一參數使用「T」，多個參數則以「T」開頭命名（如 TKey）。
• 縮寫處理：
  • 三個單字以上：無論縮略字或縮寫，僅第一個字母大寫（如 Sql）。
  • 兩個單字：依 Pascal 或 Camel Case 決定首字母，後續字母小寫（如 Id）。

Ordering Rules

程式碼成員的排序應遵循邏輯結構，建議順序如下：

1. Fields：Constant > Readonly Static > Static > Non-static。
2. Constructors：Static > Public > Protected > Private。
3. Members：依序為 Delegate、Event、Property、Indexer。
4. Methods：建議將同質性或有呼叫關係的方法群組在一起，而非僅依存取修飾詞（Access Modifiers）排序。
5. Using 指令：System. 開頭的命名空間優先，接著依字母排序；Alias 須放在最後。

註解規範

• 單行註解：使用 // （斜線後空一格）。應專注於解釋「為什麼要這樣做」，而非描述程式碼本身。
• 文件註解：使用 /// 產生 XML 文件。泛型型別在標籤內需以 {} 取代 <>。Private 成員無需撰寫文件註解。
• 工作清單：
  • TODO：待完成的功能。
  • UNDONE：進行中但尚未完成的任務。
  • HACK：暫時性的權宜之計，應盡快移除。

排版與格式

左大括弧與空格

• 左大括弧 { 應與關鍵字置於同一行。
• 空格規範：逗號後、控制流程關鍵字後、冒號前後、for 迴圈分號後均需加空格；++ 與 -- 與變數間不加空格。

運算子換行

• 二元運算子：換行時，將運算子置於新行開頭（如 +、||）。
• 賦值運算子：換行時，將 = 置於行尾。
• Lambda 箭頭：換行時，將 => 置於新行開頭，以利與賦值運算區隔。

三元運算子

巢狀三元運算子必須換行，以提升閱讀性：

bool result = condition1
    ? result1
    : condition2
        ? result2
        : result3;

空行與長度

• 空行：成員之間加一行空行，檔案末端必須保留一個空行，以避免在 Unix/Linux 環境下發生最後一行被隱藏的問題。
• 程式碼長度：建議設定 80 至 120 字元的分隔線，避免過長的程式碼導致閱讀困難。

---

異動歷程

1. 2022-11-06

   • 初版文件建立。